From e3af0d069909cc4b108dbfe089c9754c9ddbdcbb Mon Sep 17 00:00:00 2001 From: Stevan Earl Date: Tue, 11 Aug 2026 16:25:19 -0700 Subject: [PATCH] docs: distinguish unknown and no-focal observations --- doc/src/tables/events.m4 | 13 +++++++++++++ doc/src/tables/watches.m4 | 17 +++++++++-------- doc/src/views/obs.m4 | 9 +++++---- 3 files changed, 27 insertions(+), 12 deletions(-) diff --git a/doc/src/tables/events.m4 b/doc/src/tables/events.m4 index 46f7a37..7074924 100644 --- a/doc/src/tables/events.m4 +++ b/doc/src/tables/events.m4 @@ -48,6 +48,11 @@ sdb_generated_rst()dnl This means the |EVENTS.WID| column must reference a |WATCHES| row with a |WATCHES|.\ |WATCHES.Type| value of ``sdb_location``. +.. |_watch_identifies_individual| replace:: + The related |WATCHES| row should identify an individual. + The system will generate a warning when the |WATCHES|.\ + |WATCHES.AnimID| value is ``sdb_no_focal``. + .. _EVENTS: @@ -100,6 +105,8 @@ The following table lists these rules and implications: ``sdb_arrival_a`` (Arrival at the feeding station) |_a_record_protocol| + |_watch_identifies_individual| + A related row should exist on |ARRIVALS_A|; there should be a row on |ARRIVALS_A| with an |ARRIVALS_A|.\ |ARRIVALS_A.EID| value of the event's |EVENTS.EID|. @@ -253,6 +260,8 @@ The following table lists these rules and implications: ``sdb_arrival`` (Arrival) |_b_record_protocol| + |_watch_identifies_individual| + A related row should exist on |ARRIVALS|; there should be a row on |ARRIVALS| with an |ARRIVALS|.\ |ARRIVALS.EID| value of the event's |EVENTS.EID|. @@ -351,6 +360,8 @@ The following table lists these rules and implications: ``sdb_food`` (Food) |_b_record_protocol| + |_watch_identifies_individual| + A related row should exist on |FOOD_EVENTS|; there should be a row on |FOOD_EVENTS| with a |FOOD_EVENTS|.\ |FOOD_EVENTS.EID| value of the event's |EVENTS.EID|. @@ -429,6 +440,8 @@ The following table lists these rules and implications: ``sdb_groom_scan`` (SCAN interval Groomings) |_b_record_protocol| + |_watch_identifies_individual| + A related row should exist on |GROOM_SCANS_B|; there should be a row on |GROOM_SCANS_B| with an |GROOM_SCANS_B|.\ |GROOM_SCANS_B.EID| value of the event's |EVENTS.EID|. diff --git a/doc/src/tables/watches.m4 b/doc/src/tables/watches.m4 index 93c4135..1f80aa3 100644 --- a/doc/src/tables/watches.m4 +++ b/doc/src/tables/watches.m4 @@ -147,14 +147,15 @@ The |WATCHES.Type| categories are: follow. If no follow was conducted and there is no related |BRECORD_NOTES| - row, then the |WATCHES.AnimID| is expected to be that of the unknown - individual, ``sdb_unk``. + row, then the |WATCHES.AnimID| is expected to be ``sdb_no_focal`` + because no focal individual is associated with the watch. This means that the system will generate a warning when there is no |ARRIVALS| or |BRECORD_NOTES| row related to the |WATCHES| row, - and the WATCHES.\ |WATCHES.AnimID| value is *not* ``sdb_unk``. + and the WATCHES.\ |WATCHES.AnimID| value is *not* + ``sdb_no_focal``. Like any other |WATCHES.AnimID| value, there is at most one row per - day involving the unknown individual. + day involving the no focal individual, ``sdb_no_focal``. The focal of a follow is expected to have been observed during the follow. @@ -171,12 +172,12 @@ The |WATCHES.Type| categories are: warning is generated when the |WATCHES.AnimID| is the unknown individual ,``sdb_unk``. - When no follow occurred, the |WATCHES.AnimID| value is expected to - be, in some sense, meaningless. + When no follow occurred and no individual is associated with the + observation, the |WATCHES.AnimID| value is expected to be + ``sdb_no_focal``. This means the system will generate a warning when a WATCHES row of this type does not have a |ARRIVALS| related row and the - |WATCHES.AnimID| value is not that of the unknown individual, - ``sdb_unk``. + |WATCHES.AnimID| value is not ``sdb_no_focal``. These sorts of watches rows may appear when there are ad-hoc observations of behaviors like pantgrunts, matings, aggressions, and so forth. diff --git a/doc/src/views/obs.m4 b/doc/src/views/obs.m4 index bde782e..4d37869 100644 --- a/doc/src/views/obs.m4 +++ b/doc/src/views/obs.m4 @@ -54,10 +54,11 @@ values, have other rules regarding the identity of the individual recorded in the OBS.\ |WATCHES.AnimID| column. See the documentation of the |EVENTS| table for more information. -Many events are expected to have the unknown individual, ``sdb_unk``, -as their OBS.\ |WATCHES.AnimID| value -- indicating that the field team -had no particular intention to conduct an observation but, instead, -happened to observe the event. +Many events are expected to have ``sdb_no_focal`` as their OBS.\ +|WATCHES.AnimID| value, indicating that no focal or other +watch-associated individual existed. This differs from ``sdb_unk``, +which indicates that an individual existed in the role represented by +|WATCHES.AnimID| but the individual's identity is unknown. An example of this could be a pantgrunt event observed while the field researchers were on some errand. -- 2.34.1